/* Copyright (c) 2025 Beijing Semidrive Technology Corporation
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/** *****************************************************************************************************
 *  \file     Mcu_GeneralTypes.h                                                                           *
 *  \brief    This file contains interface header for MCU MCAL driver, ...                             *
 *                                                                                                      *
 * <table>                                                                                              *
 * <tr><th>Date           <th>Version                                                                   *
 * <tr><td>2023/08/02     <td>1.0.0                               *
 * </table>                                                                                             *
 *******************************************************************************************************/

#ifndef MCU_GENERALTYPES_H
#define MCU_GENERALTYPES_H
/********************************************************************************************************
 *                                      Include header files                                            *
 *******************************************************************************************************/

#include "Std_Types.h"
#include "RegHelper.h"

#ifdef __cplusplus
extern "C"
{
#endif
/********************************************************************************************************
 *                                 Global Macro definition                                              *
 *******************************************************************************************************/
#define MCU_MODULE_ID 101
#define MCU_INSTANCE 1

/* Error Code */
/** Traceability       : SWSR_MCU_006*/
#define MCU_E_PARAM_CONFIG 0x0Au
/** Traceability       : SWSR_MCU_006*/
#define MCU_E_PARAM_CLOCK 0x0Bu
/** Traceability       : SWSR_MCU_006*/
#define MCU_E_PARAM_MODE 0x0Cu
/** Traceability       : SWSR_MCU_006*/
#define MCU_E_PARAM_RAMSECTION 0x0Du
/** Traceability       : SWSR_MCU_006*/
#define MCU_E_PLL_NOT_LOCKED 0x0Eu
/** Traceability       : SWSR_MCU_006*/
#define MCU_E_UNINIT 0x0FU
/** Traceability       : SWSR_MCU_006*/
#define MCU_E_PARAM_POINTER 0x10U
/** Traceability       : SWSR_MCU_006*/
#define MCU_E_INIT_FAILED 0x11U

/** \brief  ERROR:Error due to API duplicated invoked Mcu_Init(). */
#define MCU_E_INIT 0x80U
/** \brief  ERROR:Error due to unexpected interrupt occurred. */
#define MCU_E_INT_UNEXPECT 0x81U
/** \brief  ERROR:Error due to timeout occurred. */
#define MCU_E_TIMEOUT 0x82U
/** \brief  ERROR:Error due to return value outrange occurred. */
#define MCU_E_OUTRANGE 0x83U
/** \brief  ERROR:Error due to register locked occurred. */
#define MCU_E_REGLOCKED 0x84U

/** \brief  ERROR:Error due to unaligned */
#define MCU_E_UNALIGNED 0x90U
/** \brief  ERROR:Error due to clktree dump */
#define MCU_E_CKGEN_CONSTRUCT_CLKTREE_FAILED 0x91U

/**
* \brief Service ID (APIs) for Det reporting.
*/
#define MCU_SID_INIT                        ((uint8)0x00U)
#define MCU_SID_INIT_RAM_SECTION            ((uint8)0x01U)
#define MCU_SID_INIT_CLOCK                  ((uint8)0x02U)
#define MCU_SID_DISTRIBUTE_PLL_CLOCK        ((uint8)0x03U)
#define MCU_SID_GET_PLL_STATUS              ((uint8)0x04U)
#define MCU_SID_GET_RESET_REASON            ((uint8)0x05U)
#define MCU_SID_GET_RESET_RAW_VALUE         ((uint8)0x06U)
#define MCU_SID_PERFORM_RESET               ((uint8)0x07U)
#define MCU_SID_SET_MODE                    ((uint8)0x08U)
#define MCU_SID_GET_VERSION_INFO            ((uint8)0x09U)
#define MCU_SID_GET_RAM_STATE               ((uint8)0x0AU)
#define MCU_SID_SET_RATE                    ((uint8)0x11U)
#define MCU_SID_GET_RATE                    ((uint8)0x12U)
#define MCU_SID_MONITOR_FREQ                ((uint8)0x13U)
#define MCU_SID_MONITOR_CQM                 ((uint8)0x14U)
#define MCU_SID_KICK_CORE                   ((uint8)0x15U)
#define MCU_SID_GENERAL_READ                ((uint8)0x16U)
#define MCU_SID_GENERAL_WRITE               ((uint8)0x17U)
#define MCU_SID_GET_MONITOR_RATE            ((uint8)0x18U)
#define MCU_SID_MONITOR_READY               ((uint8)0x19U)
#define MCU_SID_MONITOR_READY_EN            ((uint8)0x20U)
#define MCU_SID_MONITOR_FREQ_EN             ((uint8)0x21U)
#define MCU_SID_MONITOR_CQM_EN              ((uint8)0x22U)
#define MCU_SID_MONITOR_DBG_MON_EN          ((uint8)0x23U)
#define MCU_SID_MONITOR_DBG_MON             ((uint8)0x24U)

#define MCU_SID_SWITCH_TO_XTAL              ((uint8)0x28U)
#define MCU_SID_SWITCH_TO_RC                ((uint8)0x29U)
#define MCU_SID_CLOCK_TO_PAD                ((uint8)0x30U)


#define CALL_RET_CHECK(ret, funcall) \
    if (E_OK == (ret)) { (ret) = (funcall); }

#define MCU_CLK_PARENT_NUM 5U

#define MCU_BIT_MASK(x) ((1UL << (x)) - 1UL)
#define MCU_DIV_ROUND_UP(n, d) (((n) + (d) - 1U) / (d))


/* Dummy error id state process */
#define MCU_DUMMY_STATEMENT(state)                                  ((state) = (state))
/********************************************************************************************************
 *                                  Global Types definition                                             *
 *******************************************************************************************************/
typedef enum
{
    MCU_MODE_RUN = 0U,    /**< \brief MCU Normal running mode */
    MCU_MODE_SLEEP = 1U,  /**< \brief Sleep Mode */
    MCU_MODE_HIB = 2U,    /**< \brief Hibernate Mode */
    MCU_MODE_RTC = 3U,    /**< \brief RTC Mode */
    MCU_MODE_LPRUN = 4U,  /**< \brief LPRUN Mode */
    MCU_MODE_ALL = 4U
} Mcu_ModeType;

/** Traceability       : SWSR_MCU_012 SWSR_MCU_013 SWSR_MCU_014*/
typedef enum
{
    MCU_POWER_ON_RESET = 0U,  /**< @brief Power On Reset (default) */
    MCU_WATCHDOG_RESET,  /**< @brief Internal Watchdog Timer Reset */
    MCU_SW_RESET,        /**< @brief Software Reset */
    MCU_RESET_UNDEFINED, /**< @brief Reset is undefined */
    MCU_SEM_RESET,       /**< @brief SEM (function safety related) reset */
    MCU_DBG_RESET,       /**< @brief Reset by Debugger */
    MCU_VDC_RESET,       /**< @brief Reset by volate detect */
    MCU_EFUSE_RESET,     /**< @brief Reset by efuse non validate detect */
    MCU_COLD_RESET,     /**< @brief Reset by ap rstgen */
    MCU_PVT_RESET,      /**< @brief Reset by PVT rstgen */
} Mcu_ResetType;

/**
 * \brief PLL Spread amplitude.
 *
 */
typedef enum
{
    CKGEN_SSC_0P0_PERCENT = 0U,     /**< SSC_DEP 0.0% */
    CKGEN_SSC_0P1_PERCENT = 1U,         /**< SSC_DEP 0.1% */
    CKGEN_SSC_0P2_PERCENT = 2U,         /**< SSC_DEP 0.2% */
    CKGEN_SSC_0P3_PERCENT = 3U,         /**< SSC_DEP 0.3% */
    CKGEN_SSC_0P4_PERCENT = 4U,         /**< SSC_DEP 0.4% */
    CKGEN_SSC_0P5_PERCENT = 5U,         /**< SSC_DEP 0.5% */
    CKGEN_SSC_0P6_PERCENT = 6U,         /**< SSC_DEP 0.6% */
    CKGEN_SSC_0P7_PERCENT = 7U,         /**< SSC_DEP 0.7% */
    CKGEN_SSC_0P8_PERCENT = 8U,         /**< SSC_DEP 0.8% */
    CKGEN_SSC_0P9_PERCENT = 9U,         /**< SSC_DEP 0.9% */
    CKGEN_SSC_1P0_PERCENT = 10U,         /**< SSC_DEP 1.0% */
    CKGEN_SSC_1P1_PERCENT = 11U,         /**< SSC_DEP 1.1% */
    CKGEN_SSC_1P2_PERCENT = 12U,         /**< SSC_DEP 1.2% */
    CKGEN_SSC_1P3_PERCENT = 13U,         /**< SSC_DEP 1.3% */
    CKGEN_SSC_1P4_PERCENT = 14U,         /**< SSC_DEP 1.4% */
    CKGEN_SSC_1P5_PERCENT = 15U,         /**< SSC_DEP 1.5% */
    CKGEN_SSC_1P6_PERCENT = 16U,         /**< SSC_DEP 1.6% */
    CKGEN_SSC_1P7_PERCENT = 17U,         /**< SSC_DEP 1.7% */
    CKGEN_SSC_1P8_PERCENT = 18U,         /**< SSC_DEP 1.8% */
    CKGEN_SSC_1P9_PERCENT = 19U,         /**< SSC_DEP 1.9% */
    CKGEN_SSC_2P0_PERCENT = 20U,         /**< SSC_DEP 2.0% */
    CKGEN_SSC_2P1_PERCENT = 21U,         /**< SSC_DEP 2.1% */
    CKGEN_SSC_2P2_PERCENT = 22U,         /**< SSC_DEP 2.2% */
    CKGEN_SSC_2P3_PERCENT = 23U,         /**< SSC_DEP 2.3% */
    CKGEN_SSC_2P4_PERCENT = 24U,         /**< SSC_DEP 2.4% */
    CKGEN_SSC_2P5_PERCENT = 25U,         /**< SSC_DEP 2.5% */
    CKGEN_SSC_2P6_PERCENT = 26U,         /**< SSC_DEP 2.6% */
    CKGEN_SSC_2P7_PERCENT = 27U,         /**< SSC_DEP 2.7% */
    CKGEN_SSC_2P8_PERCENT = 28U,         /**< SSC_DEP 2.8% */
    CKGEN_SSC_2P9_PERCENT = 29U,         /**< SSC_DEP 2.9% */
    CKGEN_SSC_3P0_PERCENT = 30U,         /**< SSC_DEP 3.0% */
    CKGEN_SSC_3P1_PERCENT = 31U,         /**< SSC_DEP 3.1% */
} Mcu_CkgenSscAmplitudeType;

/**
 * \brief PLL Spread mode.
 *
 */
typedef enum
{
    CKGEN_NO_SSC = 0U,         /**< PLL no spread */
    CKGEN_DOWN_SPREADING,     /**< PLL down spread */
    CKGEN_CENTER_SPREADING,   /**< PLL center spread */
} Mcu_CkgenSscModeType;

/**
 * \brief PLL Spread Modulation frequency.
 *
 */
typedef enum
{
    CKGEN_FREF_DIV_507 = 0U,     /**< For 16MHz ref. It's 31.5KHz */
    CKGEN_FREF_DIV_761,         /**< For 24MHz ref. It's 31.5KHz */
    CKGEN_FREF_DIV_793,         /**< For 25MHz ref. It's 31.5KHz */
    CKGEN_FREF_DIV_857,         /**< For 27MHz ref. It's 31.5KHz */
} Mcu_CkgenSscFreqType;


typedef enum
{
    CKGEN_IP_SLICE_TYPE = 0,       /**< ip slice type */
    CKGEN_SF_BUS_SLICE_TYPE = 1,   /**< sf/sp bus slice type */
    CKGEN_BUS_SLICE_TYPE = 2,      /**< except sf/sp bus slice type */
    CKGEN_CORE_SLICE_TYPE = 3,     /**< core slice type */
    CKGEN_PCG_TYPE = 4,            /**< PCG type */
    CKGEN_BCG_TYPE = 5,            /**< BCG type */
    CKGEN_CCG_TYPE = 6,            /**< CCG type */
    CKGEN_PLL_CG_TYPE = 7,         /**< PLL CG type */
    CKGEN_XTAL_CG_TYPE = 8,        /**< XTAL CG type */
    CKGEN_PLL_CTRL_TYPE = 9,       /**< PLL CTRL type */
    CKGEN_PLL_LVDS_TYPE = 10,      /**< PLL LVDS type */
    CKGEN_PLL_CLK_TYPE = 11,       /**< PLL CLK type */
    CKGEN_RC24M_TYPE = 12,         /**< RC24M type */
    CKGEN_FS24M_TYPE = 13,         /**< FS24M type */
    CKGEN_RC32K_TYPE = 14,         /**< RC32K type */
    CKGEN_FS32K_TYPE = 15,         /**< FS32K type */
    CKGEN_EXT_TYPE = 16            /**< DBG MONIOR EXT_CLK type */
} Mcu_CkgenType;

/**
 * @brief Bus slice post divide ratio.
 */
typedef enum
{
    CKGEN_BUS_DIV_4_2_1 = 0,    /**< divm/divn/divp = 4/2/1 */
    CKGEN_BUS_DIV_2_2_1 = 1     /**< divm/divn/divp = 2/2/1 */
} Mcu_ClkBusRatioType;

typedef uint32 Mcu_ClkRateType;
/* PRQA S 1535 1*/
typedef uint32 Mcu_ModeConfigType;
/** Traceability       : SWSR_MCU_018 SWSR_MCU_019 SWSR_MCU_020 */
typedef uint32 Mcu_RamSectionType;
typedef uint32 Mcu_ClockType;
/** Traceability       : SWSR_MCU_015 SWSR_MCU_016 SWSR_MCU_017 */
typedef uint32 Mcu_RawResetType;


/**
 * @brief Abstract clock common node for driver operate.
 */
typedef struct
{
    uint32 base;              /**< CKGEN register base */
    Mcu_CkgenType type;              /**< Clock node type */
    uint16 id;                /**< Clock node index */
} Mcu_ClkNodeType;

/**
 * @brief Abstract clock slice node for driver operate.
 */
typedef struct
{
    Mcu_ClkNodeType clkNode;            /**< Abstract clock common node */
    uint8 parentsNum;                   /**< Slice node parent number */
    const Mcu_ClkNodeType *parents[MCU_CLK_PARENT_NUM]; /**< Parent abstract clock common node sets */
} Mcu_ClkSliceNodeType;

/**
 * @brief Abstract xcg node.
 */
typedef struct
{
    Mcu_ClkNodeType clkNode;           /**< Abstract clock common node */
} Mcu_ClkCgNodeType;

/**
 * @brief Abstract pll node for driver operate.
 */
typedef struct
{
    Mcu_ClkNodeType clkNode;          /**< Abstract clock common node */
    const Mcu_ClkNodeType *parent;     /**< Parent abstract clock common node */
} Mcu_PllNodeType;

/**
 * @brief pll spread config.
 */
typedef struct
{
    Mcu_CkgenSscAmplitudeType amplitude;
    Mcu_CkgenSscFreqType frequency;
    Mcu_CkgenSscModeType mode;
} Mcu_PllSpreadConfigType;

/**
 * @brief Clock rate config for PLL node.
 */
typedef struct
{
    const Mcu_ClkNodeType *clkNode;    /**< Abstract clock common node */
    uint32 rate;                  /**< Clock rate for node */
    const Mcu_PllSpreadConfigType *spreadConfig; /**< pll speadConfig */
} Mcu_ClkPllRateConfigNodeType;

/**
 * @brief Clock rate config for bus node.
 */
typedef struct
{
    const Mcu_ClkNodeType *clkNode;    /**< Abstract clock common node */
    uint32 rate;                  /**< Clock rate for node */
    Mcu_ClkBusRatioType postDiv;  /**< Post divide for bus slice */
} Mcu_ClkBusRateConfigNodeType;

/**
 * @brief Clock rate config for IP node.
 */
typedef struct
{
    const Mcu_ClkNodeType *clkNode;    /**< Abstract clock common node */
    uint32 rate;                  /**< Clock rate for node */
} Mcu_ClkIpRateConfigNodeType;

/**
 * @brief Clock rate config lists for PLL node.
 */
typedef struct
{
    uint32 configNum;    /**< Config node numbers */
    /* PRQA S 1060 1*/
    Mcu_ClkPllRateConfigNodeType configNodes[10];  /**< Clock node list */
} Mcu_ClkPllConfigType;

/**
 * @brief Clock rate config lists for Bus node.
 */
typedef struct
{
    uint32 configNum;  /**< Config node numbers */
    /* PRQA S 1060 1*/
    Mcu_ClkBusRateConfigNodeType configNodes[5];  /**< Clock node list */
} Mcu_ClkBusConfigType;

/**
 * @brief Clock rate config lists for IP node.
 */
typedef struct
{
    uint32 configNum;    /**< Config node numbers */
    /* PRQA S 1060 1*/
    Mcu_ClkIpRateConfigNodeType configNodes[50];  /**< Clock node list */
} Mcu_ClkIpConfigType;

/**
 * @brief clock config lists.
 */
typedef struct
{
    const Mcu_ClkPllConfigType *clkPllConfig;
    const Mcu_ClkBusConfigType *clkBusConfig;
    const Mcu_ClkIpConfigType  *clkIpConfig;
} Mcu_ClkConfigType;

/**
 * @brief cg node.
 */
typedef struct
{
    const Mcu_ClkNodeType * const *clkNode;    /**< Abstract clock common node */
} Mcu_ClkCgConfigNodeType;

/**
 * @brief Clock CG config lists.
 */
typedef struct
{
    uint32 configNum;    /**< Config node numbers */
    /* PRQA S 1060 1*/
    const Mcu_ClkCgConfigNodeType configNodes[100];  /**< Clock node list */
} Mcu_ClkCgConfigType;

/**
 * \brief abstract reset signal
 */
typedef struct
{
    uint32          base;
    uint32          id;
} Mcu_ResetSigType;

/**
 * @brief rstsignal config lists.
 */
typedef struct
{
    uint32 configNum;    /**< Config node numbers */
    /* PRQA S 1060 1*/
    const Mcu_ResetSigType *configNodes[100];  /**< Clock node list */
} Mcu_ResetConfigType;

/** Traceability       : SWSR_MCU_008*/
typedef struct
{
    uint32 idx;
    uint32 base;
    uint32 size;
    uint8 defaultValue;
    uint8 writeSize;
} Mcu_RamConfigType;

/********************************************************************************************************
 *                                  Global Function Declarations                                        *
 *******************************************************************************************************/
/** *****************************************************************************************************
 * \brief Check that the value of register bit changes to the expected value within the specified time period.
 *
 * \verbatim
 * Syntax             : boolean Mcu_Ip_WaitForBitTimes(uint32 base, uint32 offset, uint32 val, uint32 count)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - base address
 *                      offset - offset
 *                      val - wait for value
 *                      count - number of cycle waits
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : TRUE:not timeout, FALSE:timeout
 *
 * Description        : Check that the value of register bit changes to the expected value within the specified time period.
 *
 * \endverbatim
 * Traceability       : SW_SM005
 *******************************************************************************************************/
boolean Mcu_Ip_WaitForBitTimes(uint32 base, uint32 offset, uint32 val, uint32 count);
/** *****************************************************************************************************
 * \brief get best div closer to expected frequency
 *
 * \verbatim
 * Syntax             : uint32 Mcu_Ip_CkgenGetBestDiv(uint32 srcRef, uint32 freq)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : srcRef - reference frequency
 *                      freq - rate to set
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : errID
 *
 * Description        : get best div closer to expected frequency
 * .
 * \endverbatim
 *******************************************************************************************************/
uint32 Mcu_Ip_CkgenGetBestDiv(uint32 srcRef, uint32 freq);
#ifdef __cplusplus
}
#endif

#endif /* MCU_GENERALTYPES_H */
/* End of file */
